fix(service-automation): runRegion carries the outer region's index through nesting; the parallel branch index moves to branch (#15230) - #16367

Fixes #15230

The engine half of the maintainer ruling of 2026-09-03 (recorded on #14414). The contract half — ExecutionStepLogSchema.branch, and iteration re-described as single-valued — landed with PR #15227 and is untouched here.

The defect

Two facts combined to make loop { body: [ parallel { branches } ] } unreadable.

parallel wrote its branch index into iteration, the same key loop writes its row index into — one field, two meanings, told apart only by reading regionKind first. And runRegion's tagger let the innermost region win outright: a step that already carried a parentNodeId was skipped entirely, so an enclosing region contributed nothing to it.

Together: every branch step of a loop { parallel } recorded its branch index, and no step of that branch recorded the row it ran for. A per-row failure inside a branch was attributable to a branch and never to a row — which is precisely the shape a fan-out inside a scheduled sweep has, and the one an operator most needs to read.

Measured on the unmodified tree, three rows x two branches:

leafA@iteration=0/branch=undefined
leafA@iteration=0/branch=undefined
leafA@iteration=0/branch=undefined
leafB@iteration=1/branch=undefined
leafB@iteration=1/branch=undefined
leafB@iteration=1/branch=undefined

All three of leafA's rows report iteration=0 and all three of leafB's report iteration=1: that is the BRANCH index, constant per branch. The row index — 0, 1, 2 — appears nowhere, and branch is never written at all.

The change

runRegion's tagger splits what "innermost wins" governs. The two halves answer different questions:

• IDENTITY — parentNodeId, regionKind, retryAttempt — answers which region ran this step. Innermost wins outright, exactly as before: a step a nested region already claimed keeps naming that region, and an enclosing region never relabels it.
• INDEX — iteration, branch — answers which pass of which region. Nested regions contribute different indices that are both true of the same step, so an enclosing region now fills the index the inner region left undefined instead of being turned away with the identity fields.

It is still "fill only what is undefined" on both halves, so an index a nested region did set wins: loop { loop } keeps the inner loop's iteration, unchanged.

parallel writes branch: i, not iteration: i (builtin/parallel-node.ts). This file is beyond the surface the card named, and unavoidably so: the tagger writes what grouping hands it, and the branch index is produced at this call site. The alternative — having the tagger key on regionKind === 'parallel-branch' and re-home the value — puts implicit magic in the shared tagger to keep one file out of the diff.

StepLogEntry gains branch?: number and the overloaded comment is rewritten to one meaning per key. The interface is exported, and the change is exactly one optional output key, so the dispatch's Clause-②: no stop condition ("more than one optional output key") is not met.

try / catch inside a loop is unchanged, deliberately — the control arm, not a subject. Such a region has no index of its own, so its steps keep carrying the enclosing loop's iteration with regionKind still naming the region, and gain no branch. builtin/try-catch-node.ts is in the diff for its comment only: the comment asserted "a loop's own tagger can never reach past this one to a try/catch step", which this change makes false. The forwarding it explains stays (same value, and it is what $error.iteration is bound from); only the claim about the tagger is corrected.

Pins

packages/services/service-automation/src/builtin/region-index-keys.test.ts — the ruling's own three cases, plus two guards, plus a type-level pin.

Red-first, with the predictions written before the run (they held exactly):

The last row is the card's "kept in step with the spec type by a pin, not by prose". It is a type-level assertion, so vitest cannot see it — esbuild strips types and a green pnpm test says nothing about it. It is measured by tsc, where on the unmodified tree it read:

src/builtin/region-index-keys.test.ts(70,27): error TS2344: Type 'RegionKeys' does not
  satisfy the constraint 'keyof StepLogEntry'.
  Type '"branch"' is not assignable to type 'keyof StepLogEntry'.

Both tsconfig.json and tsconfig.test.json reach src/** with no test exclusion, so the pin is genuinely compiled — the errors above came out of that file, which is the positive proof.

Two fixtures replaced, not re-spelled

Both pinned exactly the branch the ruling deleted, so re-spelling the assertion would have left the retired overload free to come back as a second writer.

• builtin/parallel-node.test.ts asserted the branch index on iteration for a bare parallel. It now asserts branch, and asserts iteration is absent — the absence is the half that keeps the overload from returning.
• builtin/contained-failure-visibility.test.ts carried the "A parallel branch inside a loop body overloads the step record's iteration with the branch index — the enclosing loop iteration is lost, so a branch step cannot be attributed to its row #14414 fence", whose comment read "the pre-existing overload A parallel branch inside a loop body overloads the step record's iteration with the branch index — the enclosing loop iteration is lost, so a branch step cannot be attributed to its row #14414 owns. Nothing here changed it." This is the card that retires that overload, so the fence is spent; it now reads the two indices apart over its five rows x two branches.

Swept the rule's consumption radius rather than the edited package: regionKind has no other reader in this repo outside packages/spec (whose own tests already carry the new shape, landed with PR #15227) and the docs reference, which is generated from the spec describe and already regenerated there. The objectui FlowRunsPanel grouping key is out of scope by the card and gated on a spec release.

Also in the diff

.changeset/contained-failure-visibility.md (the pending #14456 entry) ended with "parallel branch tagging is unchanged." That was true of #14456 and is falsified by this change; both entries are pending, so shipping them unedited puts a flat contradiction in one release note. Trimmed to say it was unchanged by that change and to point at this one. Nothing else in that file is touched.

Changeset

.changeset/region-tagger-branch-key.md, @objectstack/service-automation: minor — not skip-changeset shape. The engine publishes different structured data into the run step log: branch appears, and iteration changes meaning on a parallel-branch step. That is observable to any flow author or run-observability consumer, and the exported StepLogEntry gains a key. minor rather than major to match the contract half of the same ruling, which shipped its declaration change that way; the entry states how to read a run recorded before the change, since nothing is migrated or defaulted.

Checklist

docs/qa/platform-checklist/areas/automation.json, automation.flow-run-step-nesting -> revision 3: the loop { parallel } clause the card asks for, with the three-part verify (branch: 0 survives; every (iteration, branch) pair appears once — a constant iteration per branch is what the old engine produced, so counting distinct values alone does not catch it; the container step carries the row and no branch).

Its fixture does not exist. showcase declares loop, parallel and try_catch as three separate flows and nests none in another, so the clause scores blocked(fixture) until one lands. Filed as #16356 and recorded in the item's fixtures.requires rather than left silent — an absent clause is what let this overload sit unmeasured, so the clause is written now and the gap is named in the open. #16356 is not addressed here.

What was run, and on which tree

The gate family was derived mechanically — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, from the tool's own merge-base change set, plus the four rosters it flags as kept in a directory one of these paths is in. Every exit code captured after a single redirection, never through a pipe.

• e64991ffa — the full union, 62/62 exit 0. On the first pass two came back exit 3 PREREQUISITE NOT MET (check:dual-build-cjs-loads, check:type-check-debt, both naming an unbuilt dist/). Those are neither a pass nor a finding: the prerequisite was satisfied (turbo run build --filter='./packages/*' --filter='./packages/*/*') and both re-run as real readings. pnpm lint (eslint . --no-inline-config, whole repo, not narrowed): exit 0. pnpm --filter @objectstack/service-automation test: 121 files / 1426 tests passed. typecheck (tsc --noEmit + check:test-typecheck): exit 0.
• 93fa7157b — head. Its only delta from the above is one prose string inside automation.json (an unsupported "through two releases" claim, dropped). Re-run there: every gate that reads that file (check:platform-checklist, check-platform-checklist-watchdog, check:nul-bytes, check:doc-authoring, check:pm-governed-prose, check-affected-docs, check-drift-comment, check:keyed-text-bounds, check:pm-label-desc-cap) plus the ratchet family (check:type-check-debt, check:type-check-coverage, check:dual-build-cjs-loads, check:skills-token-ratchet, check:pm-skill-ratchet) — all exit 0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Generated by Claude Code